/*
* $Id: mdump.h 5561 2009-12-25 07:23:59Z wangmeng $
*
* this file is part of easyMule
* Copyright (C)2002-2008 VeryCD Dev Team ( strEmail.Format("%s@%s", "emuledev", "verycd.com") / http: * www.easymule.org )
*
* This program is free software; you can redistribute it and/or
* modify it under the terms of the GNU General Public License
* as published by the Free Software Foundation; either
* version 2 of the License, or (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
*/
/*!
 * \file mdump.h
 * \project WonderTrader
 *
 * \author VeryCD Dev Team (原始代码)
 * \date 2009-12-25
 * 
 * \brief Windows平台内存转储工具头文件
 * 
 * \details 本文件定义了CMiniDumper类，用于在Windows平台上捕获程序崩溃时的内存转储：
 *          - 提供程序异常时的自动内存转储功能
 *          - 支持生成标准的Windows MiniDump文件
 *          - 集成Windows调试帮助库(DBGHELP.DLL)
 *          - 提供异常过滤器和顶级异常处理
 *          - 支持自定义转储文件保存路径
 *          - 为程序调试和错误分析提供重要信息
 * 
 * \note 该模块仅在Windows平台下有效，依赖Windows API和调试库
 * \warning 需要确保系统中存在DBGHELP.DLL库文件
 */
#pragma once
#include <Windows.h>
struct _EXCEPTION_POINTERS;

/*!
 * \class CMiniDumper
 * \brief Windows平台内存转储器类
 * 
 * \details CMiniDumper提供了程序崩溃时的内存转储功能：
 *          - 自动捕获未处理的异常
 *          - 生成包含调用堆栈和内存状态的转储文件
 *          - 支持自定义应用程序名称和转储路径
 *          - 集成Windows调试帮助库进行转储操作
 *          - 提供错误信息显示和用户交互
 * 
 * \note 该类采用单例模式，全局只能有一个实例
 * \warning 仅在Windows平台下可用，需要DBGHELP.DLL支持
 */
class CMiniDumper
{
public:
	/*!
	 * \brief 启用内存转储功能
	 * \param pszAppName 应用程序名称，用于转储文件命名
	 * \param bShowErrors 是否显示错误信息对话框
	 * \param pszDumpPath 转储文件保存路径，默认为空（使用程序目录）
	 * 
	 * \details 初始化内存转储器并设置异常过滤器：
	 *          - 设置应用程序名称和转储路径
	 *          - 加载Windows调试帮助库
	 *          - 注册顶级异常过滤器
	 *          - 验证MiniDumpWriteDump函数可用性
	 * 
	 * \note 该方法应在程序启动时调用一次
	 * \warning 不允许创建多个CMiniDumper实例
	 */
	static void Enable(LPCTSTR pszAppName, bool bShowErrors, LPCTSTR pszDumpPath = "");

private:
	static TCHAR m_szAppName[MAX_PATH];		/*!< 应用程序名称，用于转储文件命名和错误显示 */
	static TCHAR m_szDumpPath[MAX_PATH];	/*!< 转储文件保存路径，为空时使用程序目录 */

	/*!
	 * \brief 获取调试帮助库句柄
	 * \param ppfnMiniDumpWriteDump 返回MiniDumpWriteDump函数指针
	 * \param bShowErrors 是否显示错误信息
	 * \return 调试帮助库句柄，失败返回NULL
	 * 
	 * \details 加载DBGHELP.DLL并获取MiniDumpWriteDump函数：
	 *          - 尝试加载DBGHELP.DLL库
	 *          - 获取MiniDumpWriteDump函数地址
	 *          - 验证函数版本兼容性
	 *          - 显示相应的错误信息
	 */
	static HMODULE GetDebugHelperDll(FARPROC* ppfnMiniDumpWriteDump, bool bShowErrors);
	
	/*!
	 * \brief 顶级异常过滤器
	 * \param pExceptionInfo 异常信息指针
	 * \return 异常处理结果代码
	 * 
	 * \details 处理未捕获的异常并生成内存转储：
	 *          - 捕获程序崩溃时的异常信息
	 *          - 生成包含调用堆栈的转储文件
	 *          - 创建带时间戳的转储文件名
	 *          - 调用外部崩溃报告工具
	 *          - 在Release模式下终止进程
	 * 
	 * \note 该函数在程序发生未处理异常时自动调用
	 * \warning Debug模式下会传递异常给调试器，Release模式下会终止进程
	 */
	static LONG WINAPI TopLevelFilter(struct _EXCEPTION_POINTERS* pExceptionInfo);
};

/*!
 * \brief 全局内存转储器实例
 * \details 提供全局访问的内存转储器对象，确保整个程序只有一个转储器实例
 */
extern CMiniDumper theCrashDumper;
